DirectOutput SDK Reference
Table of Contents
Overview
The DirectOutput SDK can be used by programmers to write applications and
application plug-ins that use DirectOutput compatible devices to display information.
These commponents can be written in C or C++.
Typically these components will be used to do the following:
- Display information from a game or application.
- Recieve "Soft Button" notifications to provide application specific control.
- Act on "Soft Button" notifications to control the application or game.
DirectOutput uses a concept of Pages to seperate data. Each application can add one or more pages to the device, and each page holds a collection of output settings.
The user navigates between pages with the NextPage and PreviousPage buttons on the device.
For more information about DirectOutput, please visit the forum at www.saitekforum.com
Please direct all DirectOutput programming questions and problems to the forum.
Setup
To build applications that use DirectOutput, you must create your application to load and import
function calls from the dynamic library DirectOutput.dll.
Device Data Sheets
DirectOutput API Reference
This section lists all the API functions and structures required to build DirectOutput enabled applications.
DirectOutput_Initialize
Syntax
HRESULT DirectOutput_Initialize(const wchar_t* wszAppName);
Parameters
wszAppName
[in] A null-terminated wide character string that specifies the name of the application. Optional
Return Values
S_OK
The call completed successfully.
E_OUTOFMEMORY
There was insufficient memory to complete this call.
E_INVALIDARG
The argument is invalid.
E_HANDLE
The DirectOutputManager prcess could not be found.
Notes
This function must be called before calling any others. Call this function when you want to initialize the DirectOutput library.
DirectOutput_Deinitialize
Syntax
HRESULT DirectOutput_Deinitialize();
Parameters
This function does not take any parameters
Return Values
S_OK
The call completed successfully.
E_HANDLE
DirectOutput was not initialized or was already deinitialized.
Notes
This function must be called before termination. Call this function to clean up any resources allocated by DirectOutput_Initialize
DirectOutput_RegisterDeviceCallback
Syntax
HRESULT DirectOutput_RegisterDeviceCallback(Pfn_DirectOutput_Device_Callback pfnCallback, void* pvParam);
Parameters
pfnCallback
[in] A pointer to the callback function to be called whenever a device is added or removed.
pvParam
[in] An application supplied context pointer that will be passed to the callback function.
Return Values
S_OK
The call completed successfully
E_HANDLE
DirectOutput was not initialized.
Notes
Passing a NULL function pointer will disable the callback.
DirectOutput_Enumerate
Syntax
HRESULT DirectOutput_Enumerate(Pfn_DirectOutput_EnumerateCallback pfnCallback, void* pvParam);
Parameters
pfnCallback
[in] A pointer to the callback function to be called for each detected device.
pvParam
[in] An application supplied contect pointer that will be passed to the callback function.
Return Values
S_OK
The call completed successfully.
E_HANDLE
DirectOutput was not initialized.
Notes
This function has changed from previous releases.
DirectOutput_GetDeviceType
Syntax
HRESULT DirectOutput_GetDeviceType(void* hDevice, LPGUID pGuidType);
Parameters
hDevice
[in] A void pointer handle that was supplied in the device change callback.
pGuidType
[out] A pointer to a GUID value that will recieve the type identifier of this device.
Return Values
S_OK
The call completed successfully.
E_INVALIDARG
An argument is invalid.
E_HANDLE
The device handle specified is invalid.
Notes
Refer to the list of type GUIDs to find out about what features are available on each device.
DirectOutput_GetDeviceInstance
Syntax
HRESULT DirectOutput_GetDeviceInstance(void* hDevice, LPGUID pGuidInstance);
Parameters
hDevice
[in] A void pointer handle that was supplied in the device change callback.
pGuidInstance
[out] A pointer to a GUID value that will recieve the instance identifier of this device.
Return Values
S_OK
The call completed successfully.
E_NOTIMPL
This device does not support DirectInput.
E_INVALIDARG
An argument is invalid.
E_HANDLE
The device handle specified is invalid.
Notes
Use pGuidInstance in IDirectInput::CreateDevice to create the IDirectInputDevice that corrresponds to this DirectOutput device.
GUID gdInstance;
HRESULT hr = DirectOutput_GetDeviceInstance(hDevice, &gdInstance);
if (hr == S_OK)
{
IDirectInputDevice* pDevice;
hr = pDirectInput->CreateDevice(gdInstance, &pDevice, NULL);
if (SUCCEEDED(hr))
{
// setup pDevice as a joystick and start polling for data.
}
}
DirectOutput_GetSerialNumber
Syntax
HRESULT DirectOutput_GetSerialNumber(void* hDevice, wchar_t* pszSerialNumber, DWORD dwSize);
Parameters
hDevice
[in] A void pointer handle that was supplied in the device change callback.
pszSerialNumber
[out] String buffer to hold the serial number of the device. The String can be empty if no serial number associated with the device.
dwSize
[in] Specify the number of characters of the string buffer. The value of this parameter shouldn't be greater than 16. Otherwise, the string buffer is truncated into 16 characters.
Return Values
S_OK
The call completed successfully.
DirectOutput_SetProfile
Syntax
HRESULT DirectOutput_SetProfile(void* hDevice, DWORD cchFilename, const wchar_t* wszFilename);
Parameters
hDevice
[in] A handle to a device.
cchFilename
[in] The number of wide characters in the filename parameter, wszFilename.
wszFilename
[in] A NULL-terminated string containing the full path and filename of the profile to activate.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support profiling.
E_INVALIDARG
cchFilename is zero OR wszFilename is NULL.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
Passing in a NULL pointer to wszFilename and 0 to cchFilename will clear the current profile.
DirectOutput_RegisterSoftButtonCallback
Syntax
HRESULT DirectOutput_RegisterSoftButtonCallback(void* hDevice, Pfn_DirectOutput_SoftButton_Callback pfnCallback, void* pvContext);
Parameters
hDevice
[in] A handle to a device.
pfnCallback
[in] A pointer to the callback function to be called whenever a "Soft Button" is pressed or released.
pvContext
[in] An application supplied context pointer that will be passed to the callback function.
Return Values
S_OK
The call completed successfully.
E_HANDLE
The device handle specified is invalid.
Notes
Passing a NULL function pointer will disable the callback.
DirectOutput_RegisterPageCallback
Syntax
HRESULT DirectOutput_RegisterPageCallback(void* hDevice, Pfn_DirectOutput_Page_Callback pfnCallback, void* pvContext);
Parameters
hDevice
[in] A handle to a device.
pfnCallback
[in] A pointer to the callback function to be called whenever the active page is changed.
pvContext
[in] An application supplied context pointer that will be passed to the callback function.
Return Values
S_OK
The call completed successfully.
E_HANDLE
The device handle specified is invalid.
Notes
Adding a page with an existing page id is not allowed. The page id only has to be unique on a per application basis.
The callback will not be called when a page is added as the active page with a call to DirectOutput_AddPage(hDevice, dwPage, wszName, FLAG_SET_AS_ACTIVE);
Passing a NULL function pointer will disable the callback.
DirectOutput_AddPage
Syntax
HRESULT DirectOutput_AddPage(void* hDevice, DWORD dwPage, DWORD dwFlags);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwFlags
[in] If this contains FLAG_SET_AS_ACTIVE, then this page will become the active page. If zero, this page will not change the active page.
Return Values
S_OK
The call completed successfully.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_INVALIDARG
The dwPage parameter already exists.
E_HANDLE
The device handle specified is invalid.
Notes
Only one page per-application per-device should have dwFlags contain FLAG_SET_AS_ACTIVE. The plugin is not informed about the active page change if the FLAG_SET_AS_ACTIVE is set.
DirectOutput_RemovePage
Syntax
HRESULT DirectOutput_RemovePage(void* hDevice, DWORD dwPage);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
Return Values
S_OK
The call completed successfully.
E_INVALIDARG
The dwPage argument does not reference a valid page id.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_SetLed
Syntax
HRESULT DirectOutput_SetLed(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD dwValue);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the LED. Refer to the data sheet for each device to determine what LEDs are present.
dwValue
[in] The numeric value of a given state of a LED. Refer to the data sheet for each device to determine what are legal values.
Return Values
S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not specifiy a valid LED id.
E_HANDLE
The device handle specified is invalid.
Notes
dwValue is usually 0 (off) or 1 (on).
DirectOutput_SetString
Syntax
HRESULT DirectOutput_SetString(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD cchValue, const wchar_t* wszValue);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the string. Refer to the data sheet for each device to determine what strings are present.
cchValue
[in] The number of characters (wchar_t) in the string data.
wszValue
[in] A null-terminated wide character string that specifies the value to display. Providing a null pointer will clear the string.
Return Values
S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not reference a valid string id.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_SetImage
Syntax
HRESULT DirectOutput_SetImage(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD cbValue, const LPBYTE pbValue);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the image. Refer to the data sheet for each device to determine what images are present.
cbValue
[in] The number of bytes in pbValue
pbValue
[in] An array of bytes of cbValue bytes long that represents the raw bitmap to display on the screen.
Return Values
S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not reference a valid image id.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
The buffer passed must be the correct size for the specified image.
This call sends the buffer directly to the device, so the format of the data is
device specific. Refer to the device data sheet for more details on the image
data format.
DirectOutput_SetImageFromFile
Syntax
HRESULT DirectOutput_SetImageFromFile(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD cchFilename, const wchar_t* wszFilename);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the image. Refer to the data sheet for each device to determine what images are present.
cchFilename
[in] The number of characters (wchar_t) in the filename string.
wszFilename
[in] The NULL-terminated full path to the image to load.
Return Values
S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not reference a valid image id.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
This call reads all the data from the file and sends this directly to the device, so the format of the data is device specific.
Refer to the device data sheet for more details on the image data format.
Unless specified by the device data sheet you cannot use this function to directly send image files to the device.
DirectOutput_StartServer
Syntax
HRESULT DirectOutput_StartServer(void* hDevice, DWORD cchFilename, const wchar_t* wszFilename, LPDWORD pdwServerId, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
cchFilename
[in] The number of characters (wchar_t) in the filename string.
wszFilename
[in] The NULL-terminated full path to the Server application.
pdwServerId
[out] A pointer to a DWORD that recieves this server id.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_CloseServer
Syntax
HRESULT DirectOutput_CloseServer(void* hDevice, DWORD dwServerId, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
dwServerId
[in] The server id to close.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_SendServerMsg
Syntax
HRESULT DirectOutput_SendServerMsg(void* hDevice, DWORD dwServerId, DWORD dwRequest, DWORD dwPage, DWORD cbIn, const void* pvIn, DWORD cbOut, void* pvOut, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
dwServerId
[in] The server id to close.
dwPage
[in] The page id that is related to this server.
cbIn
[in] The number of bytes in the input buffer.
pvIn
[in] The input buffer of this message.
cbOut
[in] The number of bytes in the output buffer.
pvOut
[out] A pointer to a caller allocated buffer that recieves the output data.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_PAGENOTACTIVE
The specified page is not active and the server application attempted to access the display.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
The page does have to be active if the server accesses the display.
The page does not have to be active if the server does not access the display.
DirectOutput_SendServerFile
Syntax
HRESULT DirectOutput_SendServerFile(void* hDevice, DWORD dwServerId, DWORD dwRequest, DWORD dwPage, DWORD cbInHdr, const void* pvInHdr, DWORD cchFile, const wchar_t* wszFile, DWORD cbOut, void* pvOut, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
dwServerId
[in] The server id to close.
dwPage
[in] The page id that is related to this server.
cbInHdr
[in] The number of bytes in the input buffer header.
pvInHdr
[in] The input buffer of this message's header.
cchFile
[in] The number of characters (wchar_t) in the filename.
wszFile
[in] A NULL-terminated string of the full path to the file to send.
cbOut
[in] The number of bytes in the output buffer.
pvOut
[out] A pointer to a caller allocated buffer that recieves the output data.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_PAGENOTACTIVE
The specified page is not active and the server application attempted to access the display.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
The page does have to be active if the server accesses the display.
The page does not have to be active if the server does not access the display.
DirectOutput_SaveFile
Syntax
HRESULT DirectOutput_SaveFile(void* hDevice, DWORD dwPage, DWORD dwFile, DWORD cchFilename, const wchar_t* wszFilename, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
dwPage
The page id of the page to associate with this file.
dwFile
[in] The caller supplied file id to use for this file.
cchFilename
[in] The number of characters (wchar_t) in the filename.
wszFilename
[in] A NULL-terminated string of the full path to the file to save.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support saving files.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_DisplayFile
Syntax
HRESULT DirectOutput_DisplayFile(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD dwFile, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] The page id of the page to associate with this file.
dwIndex
[in] The index of the image to display this file on.
dwFile
[in] The caller supplied file id to use for this file.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support displaying files.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_DeleteFile
Syntax
HRESULT DirectOutput_DeleteFile(void* hDevice, DWORD dwPage, DWORD dwFile, PSRequestStatus psStatus);
Parameters
hDevice
[in] A handle to a device.
dwPage
[in] The page id of the page to associate with this file.
dwFile
[in] The caller supplied file id to use for this file.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.
Return Values
S_OK
The call completes successfully.
E_NOTIMPL
The device does not support deleting files.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.
Notes
DirectOutput_Enumerate_Callback
Syntax
void __stdcall DirectOutput_Enumerate_Callback(void* hDevice, void* pvContext);
Parameters
hDevice
[in] A handle to the device that changed.
pvContext
[in] The application defined context value passed to DirectOutput_Enumerate
Return Values
This callback does not return a value.
Notes
This callback will be called whenever a DirectOutput is present during a call to DirectOutput_Enumerate.
DirectOutput_Device_Callback
Syntax
void __stdcall DirectOutput_Device_Callback(void* hDevice, bool bAdded, void* pvContext);
Parameters
hDevice
[in] A handle to the device that changed.
bAdded
[in] true if the device was added, false if the device was removed.
pvContext
[in] The application defined context value passed to DirectOutput_RegisterDeviceCallback
Return Values
This callback does not return a value.
Notes
This callback will be called whenever a DirectOutput device is added to, or removed from, the system. Once a device has been removed, do not call any functions using the specified device handle (hDevice).
DirectOutput_SoftButton_Callback
Syntax
void __stdcall DirectOutput_SoftButton_Callback(void* hDevice, DWORD dwButtons, void* pvContext);
Parameters
hDevice
[in] A handle to the device that changed.
dwButtons
[in] A bit mask that specifies what buttons are pressed. Refer to the device data sheet to determine the allowed buttons.
pvContext
[in] The application defined context value passed to DirectOutput_RegisterSoftButtonCallback
Return Values
This callback does not return a value.
Notes
This callback will be called whenever a soft button's state changes. You will only recieve this notification if one of the pages you added is currently active.
DirectOutput_Page_Callback
Syntax
void __stdcall DirectOutput_Page_Callback(void* hDevice, DWORD dwPage, bool bActivated, void* pvContext);
Parameters
hDevice
[in] A handle to the device that changed.
dwPage
[in] The page identifier passed to DirectOutput_AddPage of this page.
bActivated
[in] true if this page has become the active page, false if this page was the active page.
pvContext
[in] The application defined context value passed to DirectOutput_RegisterPageCallback
Return Values
This callback does not return a value.
Notes
This callback is called when a page changed. You will only recieve notifications about pages you added.
Samples
Samples can be found under the <SDK>\Samples folder